AppendPARUnique
Use this procedure/function to append text into a multiline field from a paragraph resource. This procedure also renames the fields imported from the paragraph text area so they have unique names. You can use this procedure in these specific situations:
This procedure lets you import paragraphs with embedded fields, when you know that those fields should never inherit data from fields in the existing section and you expect the user to tab through the imported field and enter new data.
This procedure lets you import the same paragraph multiple times and have the field data for each instance uniquely named.
Note: When it renames fields, this procedure makes sure the field names are unique for the entire form, not just the section that contains the text area. This prevents naming conflicts with prior sections.
This procedure only works on multiline text fields.
Syntax:
AppendPARUnique (PAR, InsertFld, Field, section, Form, Group)
The system optionally returns a one (1) if successful and zero (0) if unsuccessful.
This procedure opens the section and appends the text from the first text area field found in that section. If successful, the new text will be formatted appropriately in the destination field.
The system locates the section in the directory where sections (FAP files) are typically found. Use the Refresh procedure to make sure all appended text appears in the field.
This procedure is similar to the AppendTxm procedure. For instance, suppose your paragraph section looks like this, where X1 is a reference to the Name field and X2 is a reference to the City field.
X1 of X2. X1 please let me know if you received this by mistake.
The Name field is embedded twice and the City field once. If you were to use the AppendTxm procedure on this section three times, the result would look like this:
X1 of X2. X1 let me know if you received this by mistake.
X1 of X2. X1 let me know if you received this by mistake.
X1 of X2. X1 let me know if you received this by mistake.
However, there would be only one Name and City field defined on the section. If you set Name to Tom and City to Marietta, the paragraph would look like this.
Tom of Marietta. Tom let me know if you receive this by mistake.
Tom of Marietta. Tom let me know if you receive this by mistake.
Tom of Marietta. Tom let me know if you receive this by mistake.
Using the AppendTxmUnique procedure, if you append this section three times, the first line would likely still reference Name and City (it would depend upon whether there was already a field named Name or City on the section).
The second occurrence however, would be renamed to NAME #002 and CITY #002. The third occurrence would be renamed to NAME #003 and CITY #003.
So, instead of two fields, you now have six fields to tab through and each subsequent occurrence can hold a different value.
Tom of Marietta. Tom let me know if you receive this by mistake.
John of Athens. John let me know if you receive this by mistake.
Albert of Atlanta. Albert let me know if you receive this by mistake.
Notice that multiple references to the same field in a paragraph still associate to the same field. So although there are three embedded locations in each paragraph, there are only two separate fields being referenced.
Note: This procedure renames the field uniquely for the entire form, not just the section that contains the multiline text field. For instance, suppose you have a paragraph with one embedded field. The first time you append it, it is named Field (assuming field is the original name and does not conflict). Each time you append it you get a unique name:
FIELD #002
FIELD #003
and so on...
Eventually, an AppendParUnique procedure could cause a the text to overflow to a new page. Let's assume you were up to FIELD #010 when that occurred. If you run the AppendParUnique procedure again, the name FIELD does not occur on the second page, but it did on the first. You want FIELD #011 to be next. This is why the names are unique at the form level and not the section level.
Example
Here are some examples:
Procedure |
Result |
Explanation |
#rc = AppendParUnique ("message", , "name_line"); Refresh ( ); |
1 if successful, 0 if not. |
The paragraph text from Message.PAR file is appended to the Name_line multiline text field. |
#rc = AppendParUnique (".\mstrres\messages\msg1", , "name_line", "mailer section"); Refresh ( ); |
1 if successful, 0 if not. |
The paragraph text in the MSG1.PAR file located in the \mstrres\message\ directory is appended to the Name_line multiline text field, which is in the Mailer section FAP file. |
#rc = AppendParUnique ("message", "address1" , "name_line"); Refresh ( ); |
1 if successful, 0 if not. |
The paragraph text in the Message.PAR file is appended to the Name_line multiline text field. Any embedded variable fields in the text area are inserted before the Address1 variable field, based on the tabbing sequence |
If you specifically name a section resource by appending the file extension .FAP to the name, the system will assume that you really meant to do the equivalent of AppendTXMUnique and will include the content from a section file.